HashiCorp Vault Encryption

This guide explains how to install and configure HashiCorp Vault ("Vault"). This application is used for encrypting and decrypting properties within the Itential Automation Platform (IAP).

Install Vault

To install Vault:

1. You must be logged in as root. Using sudo or a different account with the same access as root will not work.

   Figure 1: Root User

   

2. Install yum-config-manager to manage your repositories.

   yum install -y yum-utils

   Figure 2: Install Command

   

3. Use yum-config-manager to add the official HashiCorp Linux repo.

   yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo

   Figure 3: Add Vault Repo

   

4. Install Vault.

   yum -y install vault

   Figure 4: Install Vault

   

5. Verify installation.

   vault --version

   Figure 5: Verify Install

   

Configure Vault

To configure Vault:

1. Navigate to /opt/vault.

   Figure 6: Change Directory

   

2. Create a config file with an hcl file extension.

   Figure 7: Create Config File

   

3. Edit the config by adding the information below.

   ```storage "raft" {
   path = "/opt/vault/data"
   node_id = "node1"
   }

   listener "tcp" {
   address = "127.0.0.1:8200"
   tls_disable = "true"
   }

   api_addr = "http://127.0.0.1:8200"
   cluster_addr = "https://127.0.0.1:8201"
   ui = true
   ```

   Figure 8: Edit Config File

   

4. Run Vault using the command vault server -config=/opt/vault/config.hcl. This will start the Vault Server using the newly created config file.

   vault server -config=/opt/vault/config.hcl

   Figure 9: Start Vault

   

5. Once the Vault Server is running, open a second terminal window. Do not close the first terminal window as this will stop the Vault Server.

   Figure 10: Vault Server is Running

   

Unseal Vault Server

To unseal the Vault server:

1. In the second terminal window run the following commands:

   export VAULT_ADDR='http://127.0.0.1:8200'
   vault operator init

   Figure 11: Run Commands Second Terminal Window

   

2. Copy the outlined key information from the terminal window into a text file. You will need to use this information more than once.

   Figure 12: Copy Key Information

   

3. Run the unseal command vault operator unseal three (3) times using the unseal key information copied to the text file. You will need to use three (3) different unseals keys. It does not matter which three you use, but make sure each one is different.

   ---

   Note: By default there are five (5) keys with a threshold of three (3) keys. Once three (3) keys are entered the vault is unsealed. The progress of unsealing is outlined in the image below.

   ---

   Figure 13: Unseal Progress

   

4. Login to Vault using the initial root token (it should have been copied to the text file with the unseal keys). Use vault login <INITIAL_ROOT_TOKEN>.

   Figure 14: Login to Vault

   

5. Run the vault operator generate-root -init to obtain a One Time Password (OTP).

   Figure 15: Get OTP

   

6. Run the command vault operator generate-root to obtain the encoded key. This step will need to be performed three (3) times using the unseal keys. You may use the same three keys from before. Copy the encoded key to your text file.

   Figure 16: Get Encoded Key

   

7. Use the command vault operator generate-root -decode=$ENCODED_TOKEN -otp=$OTP to obtain a new root key. Remember to replace the variable with your encoded token and OTP.

   Figure 17: Get New Root Key

   

8. Once the new root key is generated (outlined in the image below), create a token.txt file for storage. The location of the token file should be in /opt/vault directory.

   Figure 18: Store New Root Key

   

Enable KV Secrets Engine

To enable the KV Secrets Engine for Vault:

1. Run the command vault secrets enable kv-v2 to enable the KV Secrets Engine. V2 is the recommended version for Vault.

   Figure 19: Enable KV Engine

   

2. Navigate to /opt/pronghorn/current and edit the properties.json file with the location of the token.txt file. More information on the token file can be found in the Vault properties section below.

   Figure 20: Edit Properties

   

Vault Properties

To use Vault, there must be a vaultProps section within the properties.json file.

Property	Required	Default	Description
url	Yes	http://localhost:8200	The default URL to connect to Vault, including the hostname and port.
token	Yes	/file/path/token.txt	The file path to a document containing a token. The token is used for authentication to access Vault secrets.
endpoint	Yes	secret/data	The endpoint for the Secrets Engine type that is used.

The vaultProps can be configured with the following properties:

"vaultProps": {
    "url": "http://localhost:8200",
    "token": "/opt/vault/token.txt",
    "endpoint": "kv-v2/data"
  }

Since pathing to the Secrets Engine can be whatever you set as a unique endpoint, the following URL sample is presented with v1 as a hard-coded file path in IAP where the actual vault token is stored.

Example: URL Structure

http://localhost:8200/v1/kv-v2/data

For more information on using Vault:

• See the official HashiCorp Vault Secrets Engine documentation.

• Refer to the Secrets Engines tutorial.

Creating a Secret Using the Vault UI

To create a secret within Vault:

1. Go to the Vault Server UI connected with IAP and login.

   Figure 21: Vault UI

   

2. Click anywhere on the KV bar.

   Figure 22: Secrets Engine KV Bar

   

3. Click the Create secret + button.

   Figure 23: Create Secret

   

4. Choose a path from the dropdown or enter manually. This must be unique, and it will be important for future steps.

5. Enter the number of versions to keep for the secret metadata.

6. In the key filed in the secret data section, enter the secret data information. For this example test_pass was used.

7. Click the eye icon (button) to make sure the information was added correctly. You can include multiple keys within one path, or use the Add button to enter additional secret data.

8. Click the Save button when you are finished.

   Figure 24: Save Secret

   

9. Secrets may be entered using JSON. The Version 1 dropdown menu pertains to the iteration of the secret entered not the version of the KV Vault Engine.

   Figure 25: JSON Toggle Switch

   

10. The newly created secret will appear alphabetically in the list. From the dropdown menu a variety of functions maybe peformed, such as deleting and viewing details.

    Figure 26: Secrets List

    

Adapters

To set encryption for Adapters:

1. Go to Admin Essentials, click the Adapters menu, and select an Adapter.

   Figure 27: Select Adapter

   

2. Within the adapter you selected, locate the value you would like to encrypt. Click the Advanced View toggle switch to see the JSON, which may be easier to edit.

   Figure 28: Advanced Configuration View

   

3. Remove the existing value. Replace it with "$SECRET_" and then the path within Vault to where that secret is stored, followed by " $KEY_" (HINT: there is a space before "$KEY") and the key within that path. An example would be "$SECRET_default_password $KEY_key" which will evaluate to "password".

   Figure 29: Edit Adapter

   

4. Click Save and the adapter will automatically restart using Vault to decrypt the changed property.

5. The adapter should appear in the list with a green status indicator and connection icons after restart.

   Figure 30: Adapter Connected

   

Profiles

To set encryption for Profiles:

1. Go to Admin Essentials, click the Profiles tab, and select the currently running profile.

2. Within this profile, click Configure, and then select one of the profile properties, such as RabbitMQ.

   Figure 31: Edit Profile Properties

   

3. Choose a RabbitMQ property to encrypt, such as "password".

4. Remove the existing value. Replace it with "$SECRET_" and then the path within Vault to where that secret is stored, followed by " $KEY_" (HINT: there is a space before "$KEY") and the key within that path. An example would be "$SECRET_default_password $KEY_key" which will evaluate to "password".

5. Save the profile.

   Figure 32: Save Profile Properties

   

6. Restart IAP for these changes to take effect.

Properties.json

To set encryption for a property:

1. Open the properties.json and select a property to encrypt, such as "mongoProps.credentials.passwd".

   ---

   Note: It is not possible to encrypt any of the vaultProps within the properties.json.

   ---

2. Remove the existing value. Replace it with "$SECRET_" and then the path within Vault to where that secret is stored, followed by " $KEY_" and the key within that path. An example would be "$SECRET_default_password $KEY_key" which will evaluate to "password".

3. Save the document.

4. Restart IAP for these changes to take effect.